home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / library / help / tcl / strings / format < prev    next >
Encoding:
Text File  |  1993-10-26  |  9.5 KB  |  187 lines  |  [TEXT/$Tcl]
  1.  
  2.           format formatString ?arg arg ...?
  3.  
  4.  
  5.      INTRODUCTION
  6.           This command generates a formatted string in the same way as
  7.           the  ANSI C sprintf procedure (it uses sprintf in its imple-
  8.           mentation).   FormatString  indicates  how  to  format   the
  9.           result, using % conversion specifiers as in sprintf, and the
  10.           additional arguments, if any, provide values to  be  substi-
  11.           tuted  into the result.  The return value from format is the
  12.           formatted string.
  13.  
  14.  
  15.      DETAILS ON FORMATTING
  16.           The command operates by scanning formatString from  left  to
  17.           right.  Each character from the format string is appended to
  18.           the result string unless it is a percent sign.  If the char-
  19.           acter  is  a  %  then it is not copied to the result string.
  20.           Instead,  the  characters  following  the  %  character  are
  21.           treated as a conversion specifier.  The conversion specifier
  22.           controls the conversion of the next successive arg to a par-
  23.           ticular  format  and  the  result  is appended to the result
  24.           string in place of the conversion specifier.  If  there  are
  25.           multiple  conversion  specifiers  in the format string, then
  26.           each one controls the conversion of one additional arg.  The
  27.           format  command  must be given enough args to meet the needs
  28.           of all of the conversion specifiers in formatString.
  29.  
  30.           Each conversion specifier may contain up  to  six  different
  31.           parts: an XPG3 position specifier, a set of flags, a minimum
  32.           field width, a precision, a length modifier, and  a  conver-
  33.           sion  character.   Any of these fields may be omitted except
  34.           for the conversion character.  The fields that  are  present
  35.           must  appear in the order given above.  The paragraphs below
  36.           discuss each of these fields in turn.
  37.  
  38.           If the % is followed by a decimal number  and  a  $,  as  in
  39.           ``%2$d'',  then  the  value to convert is not taken from the
  40.           next sequential argument.  Instead, it  is  taken  from  the
  41.           argument indicated by the number, where 1 corresponds to the
  42.           first arg.  If the conversion  specifier  requires  multiple
  43.           arguments because of * characters in the specifier then suc-
  44.           cessive arguments are used, starting with the argument given
  45.           by  the number.  This follows the XPG3 conventions for posi-
  46.           tional specifiers.  If there are any  positional  specifiers
  47.           in  formatString  then  all  of the specifiers must be posi-
  48.           tional.
  49.  
  50.           The second portion of a conversion specifier may contain any
  51.           of the following flag characters, in any order:
  52.  
  53.           -         Specifies that the converted  argument  should  be
  54.                     left-justified  in its field (numbers are normally
  55.                     right-justified with leading spaces if needed).
  56.  
  57.           +         Specifies that a number should always  be  printed
  58.                     with a sign, even if positive.
  59.  
  60.           space     Specifies that a space  should  be  added  to  the
  61.                     beginning  of  the  number  if the first character
  62.                     isn't a sign.
  63.  
  64.           0         Specifies that the number should be padded on  the
  65.                     left with zeroes instead of spaces.
  66.  
  67.           #         Requests an alternate output form.  For  o  and  O
  68.                     conversions  it guarantees that the first digit is
  69.                     always 0.  For  x  or  X  conversions,  0x  or  0X
  70.                     (respectively)  will  be added to the beginning of
  71.                     the result unless it is zero.  For  all  floating-
  72.                     point  conversions  (e, E, f, g, and G) it guaran-
  73.                     tees that the result always has a  decimal  point.
  74.                     For g and G conversions it specifies that trailing
  75.                     zeroes should not be removed.
  76.  
  77.           The third portion of a conversion specifier is a number giv-
  78.           ing  a minimum field width for this conversion.  It is typi-
  79.           cally used to make columns line up in tabular printouts.  If
  80.           the  converted  argument  contains fewer characters than the
  81.           minimum field width then it will be padded so that it is  as
  82.           wide as the minimum field width.  Padding normally occurs by
  83.           adding extra spaces on the left of the  converted  argument,
  84.           but  the  0  and - flags may be used to specify padding with
  85.           zeroes on the left or with  spaces  on  the  right,  respec-
  86.           tively.  If the minimum field width is specified as * rather
  87.           than a number, then the next argument to the format  command
  88.           determines  the  minimum  field  width; it must be a numeric
  89.           string.
  90.  
  91.           The fourth portion of a conversion specifier is a precision,
  92.           which consists of a period followed by a number.  The number
  93.           is used in different ways for different conversions.  For e,
  94.           E,  and  f  conversions it specifies the number of digits to
  95.           appear to the right of the  decimal  point.   For  g  and  G
  96.           conversions  it  specifies  the  total  number  of digits to
  97.           appear, including those on both sides of the  decimal  point
  98.           (however, trailing zeroes after the decimal point will still
  99.           be omitted unless the  #  flag  has  been  specified).   For
  100.           integer conversions, it specifies a mimimum number of digits
  101.           to print (leading zeroes will be added if necessary).  For s
  102.           conversions it specifies the maximum number of characters to
  103.           be printed; if the string  is  longer  than  this  then  the
  104.           trailing  characters  will  be dropped.  If the precision is
  105.           specified with * rather than a number then the next argument
  106.           to the format command determines the precision; it must be a
  107.           numeric string.
  108.  
  109.           The fourth part of a conversion specifier is a length modif-
  110.           ier, which must be h or l.  If it is h it specifies that the
  111.           numeric value should be truncated to a 16-bit  value  before
  112.           converting.   This  option is rarely useful.  The l modifier
  113.           is ignored.
  114.  
  115.           The last thing in a conversion specifier  is  an  alphabetic
  116.           character  that  determines  what kind of conversion to per-
  117.           form.  The following  conversion  characters  are  currently
  118.           supported:
  119.  
  120.           d         Convert integer to signed decimal string.
  121.  
  122.           u         Convert integer to unsigned decimal string.
  123.  
  124.           i         Convert integer to  signed  decimal  string;   the
  125.                     integer may either be in decimal, in octal (with a
  126.                     leading 0) or in hexadecimal (with a leading 0x).
  127.  
  128.           o         Convert integer to unsigned octal string.
  129.  
  130.           x or X    Convert integer to  unsigned  hexadecimal  string,
  131.                     using   digits   ``0123456789abcdef''  for  x  and
  132.                     ``0123456789ABCDEF'' for X).
  133.  
  134.           c         Convert  integer  to  the   8-bit   character   it
  135.                     represents.
  136.  
  137.           s         No conversion; just insert string.
  138.  
  139.           f         Convert floating-point number  to  signed  decimal
  140.                     string of the form xx.yyy, where the number of y's
  141.                     is determined by the precision (default:  6).   If
  142.                     the  precision  is 0 then no decimal point is out-
  143.                     put.
  144.  
  145.           e or e    Convert floating-point number to scientific  nota-
  146.                     tion  in  the  form x.yyye_zz, where the number of
  147.                     y's is determined by the precision  (default:  6).
  148.                     If  the  precision  is  0 then no decimal point is
  149.                     output.  If the E form is used then E  is  printed
  150.                     instead of e.
  151.  
  152.           g or G    If the exponent is less than -4 or greater than or
  153.                     equal  to  the  precision,  then convert floating-
  154.                     point number as for %e or %E.   Otherwise  convert
  155.                     as for %f.  Trailing zeroes and a trailing decimal
  156.                     point are omitted.
  157.  
  158.           %         No conversion: just insert %.
  159.  
  160.           For the numerical conversions the argument  being  converted
  161.           must be an integer or floating-point string; format converts
  162.           the argument to binary and then converts it back to a string
  163.           according to the conversion specifier.
  164.  
  165.  
  166.      DIFFERENCES FROM ANSI SPRINTF
  167.           The behavior of the format command is the same as the ANSI C
  168.           sprintf procedure except for the following differences:
  169.  
  170.           [1]  %p and %n specifiers are not currently supported.
  171.  
  172.           [2]  For %c conversions  the  argument  must  be  a  decimal
  173.                string, which will then be converted to the correspond-
  174.                ing character value.
  175.  
  176.           [3]  The l modifier is ignored;  integer values  are  always
  177.                converted as if there were no modifier present and real
  178.                values are always converted as if the l  modifier  were
  179.                present  (i.e.  type  double  is  used for the internal
  180.                representation).  If the h modifier is  specified  then
  181.                integer  values  are  truncated to short before conver-
  182.                sion.
  183.  
  184.  
  185.      KEYWORDS
  186.           conversion specifier, format, sprintf, string, substitution
  187.